PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / rjcom.exe / COM.TXT < prev next >

Wrap

Text File | 1991-12-14 | 57.8 KB | 2,043 lines

COM.LIB communications The functions described in this document allow a C program to set up and control communications that will take place through the serial ports. The routines are found in the library COM_S.LIB for small model or COM_L for the large C model. The initializa- tion function sets up an ISR that handles communications. The ISR takes the place of INT-14 and supports up to four serial interfaces. COM.LIB supports both IRQ-3 and IRQ-4 for transmit and receive and also supports other enhanced commands for the COM ports. In addition to this file, INT_14.H is a header file that must be included. It contains the necessary definitions for communication port data transfers done with this library of routines. INT_14.H specify four typedefs that will be used extensively throughout this document. They are as follows: typedef unsigned char uc; typedef unsigned int ui; typedef unsigned long ul; typedef unsigned short us; These storage classes have been defined in this manner to facili- tate casting operations and to eliminate keystrokes in normal declarations. It should be noted that the variable cn, used extensively in the following definitions to symbolize the com_number, is of the following format: ( COM1 = 0, COM2 = 1, COM3 = 2, COM4 = 3, etc... ) There are several shorthand notations used in this document. They are listed here: -> points to LSBit least significant bit MSBit most significant bit LSByte least significant byte MSByte most significant byte There are several error codes that may be returned by functions described in this document. They are listed below: NO_ERROR 0 ILLEGAL_COM_PORT -1 INPUT_QUEUE_EMPTY -2 OUTPUT_QUEUE_FULL -3 ERROR_BAUD_RATE -4 ERR_HSK_IN_PLACE -6 ERR_BAD_DATA -7 ERR_CARRIER_DROPPED -8 Global Variables -------------------------------------------------------- There are a few global variables that may be viewed or altered by the application. Because the serial ports are interrupt driven, any accesses made with a variable that is above 16-bits should be made only while interrupts are disabled. us _Com_Cprint_Output This is a bit field that determines the device that the bytes that are sent out through cprint(). If bit 0 is set, characters will be sent to the display console. If bit 1 is set, the char- acters are sent to the COM number held in _Cprint_Cn. Any combi- nation of these bits may be set or cleared. us _Com_Error_Count[] This is an array that contains the number of error conditions that have happened for each of the COM ports. ul _Com_Total_In This contains the total number of bytes that have been received from all the COM ports combined. ul _Com_Total_Out This contains the total number of bytes that have been sent out all the COM ports combined. us Com_Xfer_Timeout Default number of system ticks between sequential transmitted or received characters before modem style functions (ie cprint()) return a timeout error. us _Cprint_Cn This is the COM number that cprint() uses to communicate through. us _Xon_Percent This is the percentage of the input buffer that can be full before the ISR sends an XON to the remote. Global Variables (cont.) -------------------------------------------------------- us _Xoff_Percent This is the percentage of the input buffer that can be full when the ISR sends an XOFF to the remote. com_assert_dtr -------------------------------------------------------- Summary #include <int_14.h> short com_assert_dtr( cn ); us cn; The COM port to initialize Description This function asserts the data terminal ready signal ( DTR ) on the specified COM port cn. Asserting this signal usually informs a modem that the computer is powered up and ready for communications. Return Value The function returns a zero if completed, else the appropri- ate error code is returned See Also com_drop_dtr com_assert_rts -------------------------------------------------------- Summary #include <int_14.h> short com_assert_rts( cn ); us cn; The COM port to initialize Description This function asserts the request to send ( RTS ) on the specified COM port cn. Asserting this signal may inform the modem or other system that you want to send data. In hard- ware handshaking, asserting this signal is used to tell the sending system to send data. Return Value The function returns a zero if completed, else the appropri- ate error code is returned See Also com_drop_dtr com_clear_input ---------------------------------------------------------------- Summary #include <int_14.h> short com_clear_input( cn ); us cn; The COM port to initialize Description This function clears the input buffer that is associated with the COM port cn. The input buffer holds the bytes that are received by the port but have not yet been retrieved by the input routines. Clearing this buffer will destroy any data that has been received and not retrieved. Return Value This routine returns a zero if all went OK, else a comple- tion code will be returned explaining the error. See Also com_clear_output com_clear_output ---------------------------------------------------------------- Summary #include <int_14.h> short com_clear_output( cn ); us cn; The COM port to initialize Description This function clears the output buffer that is associated with the COM port cn. The output buffer holds the bytes that are to be sent in order to the port for output as soon as it becomes available. Return Value This function returns a zero if all is OK, else the appro- priate completion code is returned. See Also com_clear_input com_drop_dtr ---------------------------------------------------------------- Summary #include <int_14.h> short com_drop_dtr( cn ); us cn; The COM port to initialize Description This function drops the data terminal ready signal ( DTR ) of the specified COM port cn. Dropping this signal usually informs a connected modem that the computer is no longer ready for communications. Return Value The function returns the MSBit = 1 if there is an error, otherwise the status is returned, with the MSByte = modem status, and the LSByte = line status. See Also com_assert_dtr com_drop_rts -------------------------------------------------------- Summary #include <int_14.h> short com_drop_rts( cn ); us cn; The COM port to initialize Description This function drops the request to send ( RTS ) on the specified COM port cn. Asserting this signal may inform the modem or other system that you want to send data. In hard- ware handshaking, asserting this signal is used to tell the sending system to send data and dropping the signal tells the sending computer to stop sending data. Return Value The function returns a zero if completed, else the appropri- ate error code is returned See Also com_drop_dtr com_ein ---------------------------------------------------------------- Summary #include <int_14.h> us com_ein( cn ); us cn; The COM port to initialize Description This function gets the number of bytes that are still unused in the input buffer of the given COM port cn. Return Value There is no error condition here, a bad cn will yield a return of zero, if a good com number is given the returned value is the number of bytes in the input buffer. See Also com_qout com_eout com_qin com_eout ---------------------------------------------------------------- Summary #include <int_14.h> us com_eout( cn ); us cn; The COM port to initialize Description This function gets the number of bytes that are still unused in the output buffer of the given COM port cn. Return Value There is no error condition here, a bad cn will yield a zero. The returned value in all other cases will be the number of bytes contained in the output buffer. See Also com_qin com_qout com_ein com_get_settings ---------------------------------------------------------------- Summary #include <int_14.h> short com_get_settings( cn, baud_rate, data_size, stop_bits, parity ); us cn; The COM port to initialize ul *baud_rate; -> the variable to place the baud_rate uc *data_size; -> the variable to place the data_size uc *stop_bits; -> the variable to place the stop_bits uc *parity; -> the variable to place the parity Description This function places the current COM port cn settings in the variables that are provided. The baud rate 110 - 38400 will be placed into baud_rate, and the data size between 5 and 8 bits will be put into data_size. The amount of stop bits, either one or two, will be placed into stop_bits and the type of parity, either 1, 2, or 3 meaning none, odd, or even will be put into parity. Return Value This function returns the character if one is ready, and if one is not, it will return an INPUT_QUEUE_EMPTY completion code See Also com_status com_init com_in ---------------------------------------------------------------- Summary #include <int_14.h> short com_in( cn ); us cn; The COM port to initialize Description This function inputs a character from the com number cn that is specified. It will get the byte of data from the input buffer if a byte is ready. As the bytes actually come to the receiving port, they are stored in a buffer till a function such as this one remove them from it. Return Value This function returns the character if one is ready, and if one is not, it will return an INPUT_QUEUE_EMPTY completion code See Also com_sin com_snin com_qin com_ein com_init ---------------------------------------------------------------- Summary #include <int_14.h> short com_init( cn, baud_rate, data_size, stop_bits, parity, loopback_test ); us cn; The COM number to initialize ul baud_rate; The Baud rate to be set at installation uc data_size; Size of a data word, 5-8 bits uc stop_bits; The number of stop bits, 1 or 2 uc parity; Parity to use with communication ui loopback_test; The port and interrupt are verified Description This function initializes the cn to the values given by the rest of the calling parameters. The baud_rate is first given and can be a value between 110 and 38,400. The data_size can be either a 5, 6, 7, or 8 and it specifies how many bits to include in each word transferred. The stop_bits should be either a 1 or 2 and the parity can be either none, odd, or even given as 0, 1 or 2 respectively. The loopback_test the number of bytes to send in a test of the serial port and interrupt. If this value is non-zero then the port is temporarily put into the loopback mode and the number given by loopback_test is the amount of bytes that are looped back and checked for validity in the test. Return Value This function returns a zero no errors were encountered, and a error code will be returned if there was one. See Also com_status com_hangup ---------------------------------------------------------------- Summary #include <int_14.h> short com_hangup( cn ) us cn; COM number to hangup Description This function attempts to hangup a phone line connected to a Hayes compatible modem. It attempts this by first dropping DTR for one second. If DCD is still asserted, com_hangup() sends a hangup command to the modem after attempting to put the modem in command mode ("+++\nATH0\n"). If carrier is still active, com_hangup() returns with an error code. Return Value This function returns a zero no errors were encountered, and a error code will be returned if there was one. See Also com_init com_out ---------------------------------------------------------------- Summary #include <int_14.h> short com_out( cn, output_char ); us cn; The COM number to initialize uc output_char; The character to output Description This function outputs a character, given as output_char. It does this by putting the byte into the output queue. If there already is a byte waiting to be output then a byte would be stored in the output buffer and output in its turn. Return Value This function returns a 0 if no errors were encountered, else the appropriate completion code will be returned. See Also com_sout com_snout com_qout com_send_command com_qin ---------------------------------------------------------------- Summary #include <int_14.h> us com_qin( cn ); us cn; The COM port to initialize Description This function gets the number of bytes that are queued up in the input buffer of the given COM port cn. Return Value There is no error condition here, a bad cn will yield a return of zero, if a good com number is given the returned value is the number of bytes in the input buffer. See Also com_qout com_eout com_ein com_qout ---------------------------------------------------------------- Summary #include <int_14.h> us com_qout( cn ); us cn; The COM port to initialize Description This function gets the number of bytes that are queued up in the output buffer of the given COM port cn. Return Value There is no error condition here, a bad cn will yield a zero. The returned value in all other cases will be the number of bytes contained in the output buffer. See Also com_qin com_eout com_ein com_pulse_dtr ---------------------------------------------------------------- Summary #include <int_14.h> short com_pulse_dtr( cn, milliseconds ); us cn; The COM port to initialize us milliseconds; The amount of time to drop DTR Description This function first drops the DTR (data terminal ready) signal for an amount of time denoted by milliseconds and then reasserts DTR. This is done to the COM port associated with the COM number cn Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_drop_dtr com_assert_dtr com_restore_input ---------------------------------------------------------------- Summary #include <int_14.h> short com_restore_input( cn ); us cn; The COM port to initialize Description This function returns the input buffer to its original area and size. All that need be specified is the COM port given by cn. All the internal input buffer pointers are set to the empty condition and the default buffer area. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_set_input com_set_output com_restore_output com_restore_output ---------------------------------------------------------------- Summary #include <int_14.h> short com_restore_output( cn ); us cn; The COM port to initialize Description This function returns the output buffer to its original area and size. All that need be specified is the COM port speci- fied by cn. The internal buffer pointers are reset to the original default buffer area and also to the empty condition Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_set_input com_set_output com_restore_input com_send_command ---------------------------------------------------------------- Summary #include <int_14.h> short com_send_command( cn, cmd_string ); us cn; The COM port to initialize uc far *cmd_string; -> the ASCIIZ string to send out Description The purpose of this function is to allow a user to send a command string to a modem or other device at the slow rate that the device requires. This function sends the given cmd_string out at the rate of one byte every so many system ticks to the given COM port cn. This function waits for the output buffer to clear before it sends any data. Some special characters may be used in the cmd_string and will have the following definition: | = carriage return (13) ~ = delay one system tick ^ = raise DTR ` = lower DTR / = next character is taken literally Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_out com_sout com_snout com_set_baud ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_baud( cn, baud_rate); us cn; The COM port to initialize ul baud_rate; The baud rate value to set Description This function sets the baud_rate to the given value. The operation is done to the COM port, cn. Possible values of baud_rate extend from 110 to 38400 baud in the discrete values described below. 110 9600 300 11500 600 38400 1200 2400 4800 Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_init com_set_datasize com_set_carrier_vector ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_carrier_vector( cn, (*function)() ); us cn; The COM port to initialize us *function; -> the function to call Description This function sets the vector to call whenever a change in carrier is detected by the COM port, cn. The vector is called with all registers saved and the function must not return using a iret, is must use a ret instruction. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_set_carrier_vector com_set_dsr_vector com_set_datasize ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_set_datasize( cn, data_size); us cn; The COM port to initialize ul data_size; The data size to use Description This function sets the data_size to the given value. The operation is done to the COM port, cn. Possible data sizes are 5, 6, 7, and 8 bits. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_init com_set_baud com_set_dsr_vector ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_dsr_vector( cn, (*function)() ); us cn; The COM port to initialize us *function; -> the function to call Description This function sets the vector to call whenever a change in DSR is detected by the COM port, cn. The vector is called with all registers saved and the function must not return using a iret, is must use a ret instruction. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_set_carrier_vector com_set_dsr_vector com_set_input ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_input( cn, buffer, buffer_size ); us cn; The COM port to initialize uc far *buffer; -> the new buffer to use ui buffer_size; The new buffer size in bytes Description This function sets up a new input buffer for the COM port given by cn. Any data that would have been placed in the original output buffer is redirected to this new buffer area, buffer, and the size of the new buffer is given by buffer_size. The internal buffer pointers are set to this new area and also to the empty condition. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_set_output com_restore_input com_set_irq ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_irq( cn, irq_number ); us cn; The COM port to initialize uc irq_number; The IRQ number to use Description This function sets the IRQ number of the COM port cn to the value specified in irq_number. Valid IRQ numbers are 3 and 4. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_set_id com_set_port com_set_output ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_output( cn, buffer, buffer_size ); us cn; The COM port to initialize uc far *buffer; -> the new buffer to use ui buffer_size; The new buffer size in bytes Description This function sets up a new output buffer for the COM port specified by cn. Any data that would have been placed in the original output buffer is redirected to this new buffer area, buffer, and the size of the new buffer is given by buffer_size. All of the internal buffer pointers are set to the empty condition and to the new values. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_set_input com_restore_output com_set_port ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_port( cn, base_port ); us cn; The COM port to initialize ui base_port; The base port address for the COM port Description This function sets the base address for the given COM num- ber, cn to the address defined in base_port. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_set_irq com_set_id com_set_ri_vector ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_ri_vector( cn, (*function)() ); us cn; The COM port to initialize us *function; -> the function to call Description This function sets the vector to call whenever a ring is detected by the COM port, cn. The vector is called with all registers saved and the function must not return using a iret, is must use a ret instruction. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_set_carrier_vector com_set_dsr_vector com_set_waiting ---------------------------------------------------------------- Summary #include <int_14.h> short com_set_baud( wait_byte, response_byte ); uc wait_byte; Byte to respond to uc response_byte; Byte with which to respond Description This function sets a bye that will trigger an automatic response by the COM interrupt service routine (ISR). When this feature is enabled, whenever the ISR receives a byte matching wait_byte, the ISR will immediately return the byte provided in response_byte. If wait_byte is a 0, this background process will be disa- bled. Return Value This function returns a completion code of zero if all went OK, or else a negative error code will be returned. See Also com_sin ---------------------------------------------------------------- Summary #include <int_14.h> us com_sin( cn, buffer ); us cn; The COM port to initialize uc far *buffer; -> buffer for the input data Description This function gets all the bytes in the input buffer and puts them into the buffer as a ASCIIZ string. The bytes are taken from the buffer associated with the COM port cn. Return Value This function returns no error code, instead the number of bytes input is returned. A bad COM port will yield a zero. See Also com_in com_snin com_qin com_ein com_snin ---------------------------------------------------------------- Summary #include <int_14.h> us com_snin( cn, buffer, count ); us cn; The COM port to initialize uc far *buffer; -> buffer for the input data us count; The number of bytes to read Description This function gets count number of bytes from the input buffer and puts them into the buffer as a ASCIIZ string. The bytes are taken from the buffer associated with the COM port cn. Return Value This function returns no error code, instead the number of bytes input is returned. A bad COM port will yield a zero. See Also com_in com_sin com_qin com_ein com_snout ---------------------------------------------------------------- Summary #include <int_14.h> short com_snout( cn, string, count ); ui cn; The COM port to initialize uc far *string; -> string to output ui count; number of bytes to output Description This function outputs bytes from string through the COM port cn, but allows the user to specify the number of bytes to output from the string given with the variable count. The bytes that are to be output are stored in the output buffer and then the function returns, leaving the ISR to actually send the bytes in order in the background. Return Value This function returns a 0 if no errors were encountered, else the proper error code is returned to the calling func- tion. See Also com_out com_sout com_send_command com_qout com_sout ---------------------------------------------------------------- Summary #include <int_14.h> short com_sout( cn, string ); us cn; The COM port to initialize uc far *string; -> string to output Description This function outputs a string string to the COM port cn. As with the other output routines, the characters are stored in the output buffer and the function returns. The ISR working in the background takes care of outputting the characters from the buffer. Return Value The function returns a 0 if no errors were encountered or else an appropriate error code if some kind of problem develops. See Also com_out com_snout com_send_command com_qout com_start_hard ---------------------------------------------------------------- Summary #include <int_14.h> short com_start_hard( cn ); us cn; The COM port to initialize Description This function starts hardware handshaking on the serial port denoted by cn. Under this protocol the RTS/CTS signals allow the receiving system to tell the sending system if it can handle a stream of bytes at a given time. The sending system looks at RTS through CTS to see if it can send bytes, if RTS is asserted byte flow is allowed. This function will return an error if Xon/Xoff handshaking is already in progress. Return Value The function returns a 0 if no errors were encountered or else an appropriate error code if some kind of problem develops. See Also com_stop_hard com_start_xonxoff com_start_xonxoff ---------------------------------------------------------------- Summary #include <int_14.h> short com_start_xonxoff( cn ); us cn; The COM port to initialize Description This function starts Xon/Xoff handshaking on a serial port denoted by cn. Under this protocol the XON an XOFF charac- ters are exchanged between the sender and receiver during a data transfer in order to control data flow so that bytes are not overwritten at the receiving end. This function will return an error if hardware handshaking is already imple- mented. Return Value The function returns a 0 if no errors were encountered or else an appropriate error code if some kind of problem develops. See Also com_start_hard com_stop_xonxoff com_status ---------------------------------------------------------------- Summary #include <int_14.h> us com_status( cn ); us cn; The COM number to initialize Description This function gets the status of the given port. It returns the current status of the modem register and information about error that could be occurring. The bits of the status word will be described below Return Value The function returns the com port status word, and the bits of this word have the following meanings: BIT DESCRIPTION DEF. 0 Change in CTS since check COM_CHANGE_CTS 1 Change in DSR since check COM_CHANGE_DSR 2 Change in RI since check COM_CHANGE_RI 3 Change in DCD since check COM_CHANGE_DCD 4 Clear to send asserted COM_CTS 5 Data set ready asserted COM_DSR 6 Ring indicator asserted COM_RI 7 Data Carrier Detect asserted COM_DCD 8 Data is ready to be output COM_DATA_READY 9 Received byte was overwritten COM_DATA_OVERRUN 10 Parity error was detected COM_PARITY_ERROR 11 Transmission was out of sync COM_FRAME_ERROR 12 Break signal was received COM_BREAK_DETECT 13 Transmission register empty COM_XMIT_EMPTY 14 Transmission shift empty COM_SHIFT_EMPTY 15 General COM error since check COM_ERROR See Also com_init com_get_settings com_stop ---------------------------------------------------------------- Summary #include <int_14.h> short com_stop( cn ); us cn; The COM port to initialize Description This function replaces the ISR that com_init() installed with the original vector. This is important since other programs will probably not work properly if the system is not returned to original since they will expect the original vector to be in place. Return Value The function returns a 0 if no errors were encountered or else an appropriate error code if some kind of problem develops. See Also com_init com_stop_hard ---------------------------------------------------------------- Summary #include <int_14.h> short com_stop_hard( cn ); us cn; The COM port to initialize Description This function stops hardware handshaking on the serial port denoted by cn. Under this protocol the RTS/CTS signals allow the receiving system to tell the sending system if it can handle a stream of bytes at a given time. The function has no effect if the handshaking was not already started. Return Value The function returns a 0 if no errors were encountered or else an appropriate error code if some kind of problem develops. See Also com_start_hard com_stop_xonxoff ---------------------------------------------------------------- Summary #include <int_14.h> short com_stop_xonxoff( cn ); us cn; The COM port to initialize Description This function stops Xon/Xoff handshaking on a serial port denoted by cn. Under this protocol the XON an XOFF charac- ters are exchanged between the sender and receiver during a data transfer in order to control data flow so that bytes are not overwritten at the receiving end. This function has no effect when Xon/Xoff handshaking has not been started. Return Value The function returns a 0 if no errors were encountered or else an appropriate error code if some kind of problem develops. See Also com_start_xonxoff com_version ---------------------------------------------------------------- Summary #include <int_14.h> ui com_version( void ); Description This function returns the version number of the ISR that is installed and operating on the system at the time of the call. Return Value The function returns the major version number in the MSByte and the minor version number in the LSByte. See Also com_status com_init com_get_settings cprint ----------------------------------------------------------------- Summary #include <int_14.h> int cprint( control_string, var1, var2, ..., varn ); uc *control_string; -> Cprint control string var1, var2, var3... Various arguments for stack Description This is a general purpose display routine that operates much like the printf function. It supports a majority of the control characters that printf does as well as some extended features. The output of this function is directed to the console or the COM port. Also, ANSI commands are used to provide a number of useful features that are accessable through the % and \ commands. Several user oriented global variables are used by this function: _Cprint_Cn Specifies the COM port to use. The default is COM1. _Com_Cprint_Output The output device to use: 1 = console, 2 = COM port, 3 = Both. The following control sequences are supported: %% This sends a single % character, length can not be specified, to the output device. %a Sets the ANSI attribute to the next arguement in the list. %b Outputs the next value in the argument list as a binary number. %c Outputs the next value in the argument list as an ASCII character. Any number of characters may be sent using this control character. %d Outputs the next argument in the list as a decimal number. %e This clears to the end of the line. cprint (cont.) ----------------------------------------------------------------- %f Outputs the next value in the argument list as a double precision floating point number. %g Outputs the next value in the argument list as a double precision floating point number. %h This defines a place holder to be used for data entry. %i This is for data input from the user (needs data type and variable pointer). %j This moves the ANSI cursor forward a number of places. l This is a modifier that can be used with the % control characters. When it is used with %d, %x, %X, %j, or %p a long number is assumed to be in the arguement list. And, when it is used with a %s, a far * is assumed to point the string. %o The next argument in the argument list defines the output device to use. ( 1 = CONSOLE, 2 = COM port, and 3 = SEND_TO_BOTH ) %p Positions the ANSI cursor at the absolute location indicated by the next two arguments. These values are ordered X, Y. %r This restores the cursor position to is original position. %s Outputs the string pointed to by the next value in the argument list. %t Saves the current cursor position so that it may be restored. %u Outputs the next arguement in the list as an unsigned integer. %v Outputs a number of bytes from the pointer provid- ed, given that the number is less than 255. The number of bytes is specified and the string need not be terminated. %x Outputs the next value in the argument list as a lower case hexadecimal number. %A This control character will assert the DTR signal of the COM port. cprint (cont.) ----------------------------------------------------------------- %B This will start handshaking using the Xon/Xoff protocol unless handshaking is already in progress. %C The next arguement in the list will define the COM port that will recieve output from Cprint. %D This control character will cause a the DTR signal to be dropped. %H This control will cause hardware handshaking to start using RTS/CTS signals provided that other handshaking is not in progress. %S Stops all handshaking that is in progress and has no effect if there is no handshaking enabled. %T The next value in the argument list is taken to be the number of ticks to wait before a function timeout occurs. This is just a local timeout for this function call and does not affect global var- iables. %X Outputs the next value in the argument list as a upper case hexadecimal number. 1-99 Indicates display length required for the display of whatever control with which this is associated. * Indicates that the output length should be taken from the next value in the argument list. . When used with a floating point number, the number that immediately follows this period will indicate the number of decimals to display. The following special characters are supported: \b Backspace over the previous character without erasing that character. \f Clears the entire screen. \n Carriage return, line feed. \r Moves to the first column of the current line. \t Tab character. cprint (cont.) ----------------------------------------------------------------- Return Value The command string is sent out to the COM port specified, and to the Console if that is desired, or both. The other functions specified by %control characters are performed and any error that is found will be returned as such. The value of 0 will be returned if all went OK, and the appropriate negative error code will be returned if something went amiss. See Also